Media Delivery Configuration

As a content publisher, you create and configure Media Delivery sites for the Content Delivery Network (CDN) with the Sites API.

Alternatively, you can use the Media Delivery user interface to build a site configuration. Learn More.

Quick Start

Follow these steps to use the Sites API to create and configure Media Delivery for the Content Delivery Network (CDN). Please note that in alignment with the SVTA standard, the API uses the term “site” to represent the CDN site for Media Delivery.

A site is configured for a particular traffic type, such as VOD, live streaming, or low latency live streaming, to allow for optimization based on the unique characteristics of the traffic type. Thus, if you serve different types of content, you'll configure at least one site per traffic type.

The site configuration must include at least one host. A host represents a delivery service for a specified traffic type. When you configure a host, you'll specify a hostname, the traffic type, the origin (from where the CDN acquires content), and the processing rules. In addition, you may define access control lists (ACLs).

When a site configuration includes multiple hosts, each host configuration must define the same traffic type.

Step 1: Authentication

Two authentication methods are supported for interacting with Qwilt APIs:

API key based authentication
Token based authentication

Learn about Authentication

Step 2: Create a Site

Create the site object with the Create a Site function. The site object is assigned a unique ID. Later, you’ll add the site configuration parameters to the site object.

Learn about the Create a Site function.

EXAMPLE

Request URL https://media-sites.cqloud.com/api/v2/sites

Request Example

When using the API to create a site, include the mandatory "siteName" field in the body of the request. The siteName value is any user-defined string.

The default site routing method is DNS. If your site will use HTTP routing, add the "routingMethod": "HTTP" value to the request body.

In this example, we're creating a site (that will use the default DNS routing method) that we've decided to name, "My Site."

curl --request POST \
  --url https://media-sites.cqloud.com/api/v2/sites \
  --header 'X-API-KEY: eyJhbGciOiJS...' \
  --header 'Content-Type: application/json' \
  --data '{
  "siteName": "My Site"
}'

Response Body

Note these fields in the response body:

siteId: A unique ID assigned to the site. You'll need to pass this value when adding the configuration parameters to the site and when you publish the site.
siteDnsCnameDelegationTarget: This is the CNAME you'll use to direct traffic from your website to the CDN. (Alternatively, use HTTP routing.)
serviceID: Certain Qwilt logs, reports, and APIs may display the site internal ID rather than the site name.

  {
    "siteId": "123cc456fd123456c8e5c000",
    "ownerOrgId": "acme",
    "creationTimeMilli": 1669122137600,
    "lastUpdateTimeMilli": 1669122137600,
    "createdUser": "bob@acme.com",
    "lastUpdatedUser": "bob@acme.com",
    "siteDnsCnameDelegationTarget": "edge.ds-c1234-acme.global.dns.qwilted-xyz.cqloud.com",
    "siteName": "My Site",
    "apiVersion": null,
    "activeAndLastPublishingOperation": null,
    "serviceType": "MEDIA_DELIVERY",
    "monitoring": null,
    "routingMethod": "DNS",
    "shouldProvisionToThirdPartyCdn": true,
    "serviceId": "c1234-acme",
    "isSelfServiceBlocked": false
  }

Step 3: Prepare the Configuration JSON

The site configuration parameters define exactly how the CDN processes client requests and delivers content. While site configuration can be as simple as defining a single host and a single origin (a single delivery service for a specified traffic type), a typical use case may require configuring multiple hosts and origins, rules, and paths.

When a site has multiple hosts, each host is configured for the same traffic type. Likewise, the path configuration traffic type must be the same as that of the host.

The configuration parameters are passed in the body of the site configuration API request. The body must be formatted as application/json.

Learn how to prepare the configuration JSON file.

Example

A site can be fully functional with a single host and a single origin. This example illustrates the basic scenario.

The example JSON file includes the three mandatory site configuration parameters:

The site hostname is "www.acme.com"
The origin server is "www.example-origin-host.com"
The mandatory changeDescription is present

'{
  "hostIndex": {
    "hosts": [
      {
        "host": "www.acme.com",
        "host-metadata": {
          "metadata": [
            {
              "generic-metadata-type": "MI.SourceMetadataExtended",
              "generic-metadata-value": {
                "sources": [
                  {
                    "protocol": "https/1.1",
                    "endpoints": [
                      "www.example-origin-host.com"
                    ]
                  }
                ]
              }
            }
          ],
          "paths": []
        }
      }
    ]
  }  
 ,"changeDescription":"Initial site configuration - acme.com - created by BQ."
}'

(https/1.1 is the default protocol available to clients. Additional protocols are supported and can be set with the HTTP Protocols rule.)

You can copy this example JSON format to configure a simple but fully functional site. Just replace the example hostname and origin server values with your own values.

Step 4: Add the Site Configuration

Use the Add Site Configuration function to add the configuration parameters to the site object.

It is important to note that each time you add a site configuration, a unique and immutable version of the site is created. Each configuration version is assigned a unique revisionId.

Learn about the Add a Site Configuration function.

Example

Request URL

https://media-sites.cqloud.com/api/v2/sites/<siteId>/configurations

Request Example

The URL The configuration parameters are passed in the body of the API request.

curl --request POST \
  --url https://media-sites.cqloud.com/api/v2/sites/123cc456fd123456c8e5c000/configurations \
  --header 'X-API-KEY: eyJhbGciOiJS...' \
  --header 'Content-Type: application/json' \
  --data '{
  "hostIndex": {
    "hosts": [
      {
        "host": "www.acme.com",
        "host-metadata": {
          "metadata": [
            {
              "generic-metadata-type": "MI.SourceMetadataExtended",
              "generic-metadata-value": {
                "sources": [
                  {
                    "protocol": "https/1.1",
                    "endpoints": [
                      "www.example-origin-host.com"
                    ]
                  }
                ]
              }
            }
          ],
          "paths": []
        }
      }
    ]
  }  
 ,"changeDescription":"Initial site configuration - acme.com - created by BQ."
}'

Response Body

Note the revisionId. You will need this value to publish the site.

{
  "siteId":"123cc456fd123456c8e5c000",
  "revisionId":"65bfd9294e60ce37f0cc0000",
  "revisionNum":1,
  "ownerOrgId":"acme",
  "creationTimeMilli":1707071785592,
  "lastUpdateTimeMilli":1707071785592,
  "createdUser":"bob@acme.com",
  "hostIndex":{},
  "changeDescription":"Initial site configuration - acme.com - created by BQ."

Step 5: Publish the Site

Use the Publish a Site function to publish the site configuration to the CDN.

Once you publish a Media Delivery site, the CDN can begin processing requests.

To direct traffic from your website to the CDN site, update your domain's DNS settings with the CNAME of the Media Delivery site.

Learn about the Publish a Site function.

info

A site is configured for a particular traffic type, to allow for optimization based on the unique characteristics of the traffic type. Currently, these optimizations are implemented by Qwilt. Please contact your account manager or email support@qwilt.com to apply the optimizations to your new site.

Example

Request URL

https://media-sites.cqloud.com/api/v2/sites/<siteId>/publishing-operations

Request Example

The revisionId is passed in the body of the API request.

curl --request POST \
  --url https://media-sites.cqloud.com/api/v2/sites/123cc456fd123456c8e5c000/publishing-operations \
  --header 'X-API-KEY: eyJhbGciOiJS...' \
  --header 'Content-Type: application/json' \
  --data '{
  "revisionId": "65bfd9294e60ce37f0cc0000"
}'

Response Body

{
  "publishId":"24c5f84a-bac1-4513-adab-d12345678e0b",
  "ownerOrgId":"acme",
  "creationTimeMilli":1707075759661,
  "lastUpdateTimeMilli":1707075759661,
  "revisionId":"65bfd9294e60ce37f0cc0000",
  "target":"ga",
  "username":"bob@acme.com",
  "publishState":"Validation",
  "publishStatus":"InProgress",
  "publishHidden":null,
  "publishMode":"PUBLISH",
  "operationType":"Publish",
  "statusLine":[],
  "configLastModifiedTimeMilli":null,
  "isActive":false,
  "validatorsErrDetails":null,
  }

Certificate Management

Optionally, you can link an SSL certificate to the site with the Link a Certificate function. Uploading a certificate is a prerequisite to linking it to a site. Upload certificates with the Certificate Manager API.

Purge API (Cache Management)

Once your site is in production, you can use the Purge API to manage the cache with the Purge and Update functions.

Quick Start

Step 1: Authentication​

Step 2: Create a Site​

Step 3: Prepare the Configuration JSON​

Example​

Step 4: Add the Site Configuration​

Example​

Request URL​

Request Example​

Response Body​

Step 5: Publish the Site​

Example​

Request URL​

Request Example​

Response Body​

Related APIs​

Certificate Management​

Purge API (Cache Management)​

Step 1: Authentication

Step 2: Create a Site

Step 3: Prepare the Configuration JSON

Example

Step 4: Add the Site Configuration

Example

Request URL

Request Example

Response Body

Step 5: Publish the Site

Example

Request URL

Request Example

Response Body

Related APIs

Certificate Management

Purge API (Cache Management)